================================================================================
 BROKEN MEMORIES  v1.0
 4-track looper with texture and glitch effects for the Critter & Guitari
 Organelle M (Pure Data)
================================================================================

CONTENTS
  1. What it is
  2. Installation
  3. Basic ideas
  4. Control map (keyboard, footswitch, AUX, encoder, knobs)
  5. Recording and handling loops
  6. The main screen (page 0)
  7. Performance keys: glitch, freeze and random jump
  8. Per-loop effects (pages 1 to 5 and 10)
  9. Master effects and recorder (pages 6 to 9)
 10. MIDI
 11. CPU saving
 12. Tips and troubleshooting
 13. Technical data


--------------------------------------------------------------------------------
 1. WHAT IT IS
--------------------------------------------------------------------------------
Broken Memories is a 4-track stereo looper whose loops are FREE: they do not
depend on any BPM. Each loop lasts exactly as long as you hold the record key,
from about 3 milliseconds up to 24 seconds.

Each loop goes through its own effects chain built for textures, ambience and
glitch: granular, random stutter, resonant filter, delay (with ping-pong and
tape) and stereo reverb. The 4 loops are then summed into a master with filter,
delay, reverb and a very aggressive drive, an always-on limiter and its own
stereo recorder.

It also has performance functions: manual glitch, grain freeze, random jump of
the start point, footswitch input and MIDI control.


--------------------------------------------------------------------------------
 2. INSTALLATION
--------------------------------------------------------------------------------
Copy the complete "Broken Memories" folder into the Organelle's Patches folder.
Do not rename the files. The folder includes "master recs", where the master
recordings are saved; do not delete or rename it.

The whole patch is standard Pure Data. It needs no external libraries.
Stereo input and output. Master volume is the Organelle's Vol knob.


--------------------------------------------------------------------------------
 3. BASIC IDEAS
--------------------------------------------------------------------------------
* FREE LOOP. You record while you hold the key; when you release it the loop
  starts playing immediately and repeats. At 24 seconds it stops by itself.

* SELECTED LOOP. Most things (effects, glitch, freeze, jump) act on the
  selected loop. Choose it with the C#, D#, F# and G# keys of the lower octave.

* WINDOW (K4, page 0). It is which part of the loop plays, from 1% to 100%.
  At 100% the whole loop plays; at 10% only a short fragment repeats.

* PITCH (K3, page 0). Changes the read speed in whole semitones (-12 to +12).
  It raises or lowers both pitch and speed, like a record.

* MIX = 0 MEANS EFFECT OFF. Every effect starts with its Mix at 0. To hear an
  effect, raise its Mix (K1 on its page). An effect that is off also uses no
  CPU (see section 11).

* TAKEOVER. When you change page, the knobs do not move the value until you
  bring them to the stored value or cross it. On screen, a mark over each
  knob's bar shows where the physical knob is.


--------------------------------------------------------------------------------
 4. CONTROL MAP
--------------------------------------------------------------------------------
KEYBOARD (24 keys, MIDI notes 60 to 83)

   Note  Key     Function
   ----  -----   ------------------------------------------------------------
    60   C       MASTER recorder: start / stop
    61   C#      Select loop 1
    62   D       Manual GLITCH on the selected loop (while held)
    63   D#      Select loop 2
    64   E       Manual GLITCH on all 4 loops (while held)
    65   F       FREEZE grains of the selected loop (toggle)
    66   F#      Select loop 3
    67   G       FREEZE grains of all 4 loops (toggle)
    68   G#      Select loop 4
    69   A       RANDOM JUMP of the selected loop (toggle)
    70   A#      Play / stop loop 1
    71   B       RANDOM JUMP of all 4 loops (toggle)
    72   C       Master recording gain (steps through the values)
    73   C#      Play / stop loop 2
    74   D       (free)
    75   D#      Play / stop loop 3
    76   E       (free)
    77   F       (free)
    78   F#      Play / stop loop 4
    79   G       (free)
    80   G#      RECORD the selected loop (while held)
    81   A       (free)
    82   A#      RECORD all 4 loops (while held)
    83   B       CLEAR the selected loop  |  AUX + B: clear all 4

FOOTSWITCH (Organelle footswitch input)
   Footswitch:        records the selected loop while held (same as G#).
   AUX + footswitch:  records all 4 loops at once (same as A#).

AUX
   Tap and release: turns input monitoring on or off. Monitoring starts on.
   If you use AUX together with another key or the footswitch, releasing it
   does NOT change monitoring.

ENCODER
   Turn:       changes page (0 to 10; from page 0, turning left goes to 10).
   Click:      back to page 0.
   Hold 1.5 s: exit to the Organelle menu.

KNOBS (K1 to K4): they change with the page (see sections 6 and 8).


--------------------------------------------------------------------------------
 5. RECORDING AND HANDLING LOOPS
--------------------------------------------------------------------------------
RECORDING A LOOP
  1. Choose the loop with C#, D#, F# or G# (loops 1 to 4).
  2. Hold G# (upper octave, note 80) or the footswitch. You record while you
     hold it.
  3. Release: the loop plays. Its length is the time you held the key (about
     3 ms to 24 s; at 24 s it cuts off by itself).

RECORDING ALL 4 AT ONCE
  Hold A# (note 82), or AUX + footswitch. All 4 loops record the same input.

PLAY / STOP
  Keys 70, 73, 75 and 78 (A# of the lower octave; C#, D# and F# of the upper
  octave) = loops 1, 2, 3 and 4.

CLEAR
  B (note 83) clears the selected loop. AUX + B clears all 4. Clearing a loop
  also releases its freeze, its glitch and its random jump.

VOLUME AND PAN (page 0)
  Each loop's gain is 2 x vol x vol, so control is gentle at the bottom and
  generous at the top. An always-on limiter protects the master.


--------------------------------------------------------------------------------
 6. THE MAIN SCREEN (PAGE 0)
--------------------------------------------------------------------------------
KNOBS ON PAGE 0
   K1  Volume of the selected loop
   K2  Pan (C = center, L1 to L50, R1 to R50)
   K3  Pitch (-12 to +12 semitones)
   K4  Window (1% to 100%)

LEFT: one row per loop
   Loop number (the selected one is framed), a state icon (dash = empty,
   square = stopped, triangle = playing, circle = recording) and a position
   bar inside the loop (while recording it shows the recorded time).
   Letters may appear next to the number:
      F = grains frozen      G = manual glitch active
      R = random jump active

RIGHT (one line per row)
   Len / Rec     Loop length (Len) or the time you have been recording (Rec)
   REC m:ss      Master recorder time while recording; when not recording it
                 shows the recording gain (RecG +12dB)
   Sel Loop      Selected loop
   Vol           Volume of the selected loop
   Pan           Pan
   Pit           Pitch in semitones
   Win           Window in %
   Mon           Input monitoring (ON / OFF)


--------------------------------------------------------------------------------
 7. PERFORMANCE KEYS
--------------------------------------------------------------------------------
MANUAL GLITCH  (D = selected loop, E = all 4; while held)
  The loop repeats a short fragment of itself while you hold the key, even if
  GLITCH Mix is 0. It uses Slice and Chaos from page 2. On release the loop
  goes back to normal.

FREEZE GRAINS  (F = selected loop, G = all 4; toggle)
  One press freezes, the next releases. The grain cloud stays fixed at the loop
  position where you froze it, and you hear it even if GRAIN Mix is 0 (you hear
  the cloud instead of the loop). It uses Size, Dens and Scat from page 1. You
  can change those parameters while frozen.

RANDOM JUMP  (A = selected loop, B = all 4; toggle)
  While active, the loop randomly changes, every so often:
     - its START POINT (anywhere in the recording), and
     - its WINDOW LENGTH (between a minimum you choose and the K4 value).
  The time between jumps is also random and is set on page 10 (from 50 ms to
  5 s). The first jump happens instantly, so you can tell it was activated. Each
  jump lowers the gain for 4 ms and raises it again to avoid clicks. If you stop
  the loop it does not jump, but it stays armed and resumes when you restart.
  When you turn it off, or clear the loop, it returns to the original start
  and to the K4 window. The grains and glitch of that loop follow the new start
  point.


--------------------------------------------------------------------------------
 8. PER-LOOP EFFECTS (pages 1 to 5 and 10)
--------------------------------------------------------------------------------
The settings on these pages belong to the selected loop: each loop has its own.
On all of them K1 is the MIX (0 = off). Order in which they are applied:
   Granular > Glitch > Filter > Delay > Reverb > Pan.

PAGE 1  GRAIN  (granular: granulates the loop itself)
   K1 Mix
   K2 Size   Size of each grain, 8 to 400 ms
   K3 Dens   Density, 1 to 60 grains per second
   K4 Scat   Scatter: how much grain position and pitch vary randomly
             (0 = all alike, 100 = widely scattered)

PAGE 2  GLITCH  (random stutter)
   K1 Mix
   K2 Rate   Events per second, 0.3 to 16
   K3 Slice  Length of the repeated fragment, 3 to 240 ms
   K4 Chaos  Variation: length, number of repeats, pitch and muted gaps
   Note: the D key (manual glitch) uses Slice and Chaos from this page.

PAGE 3  FILTER  (resonant filter)
   K1 Mix
   K2 Sweep  Left half: low-pass (60 Hz to 18 kHz). Center: no filter.
             Right half: high-pass (20 Hz to 6 kHz).
   K3 Reso   Resonance

PAGE 4  DELAY
   K1 Mix
   K2 Time   Time, 20 ms to 1.5 s
   K3 Fdbk   Feedback, 0 to 95%
   K4 Mode   Clean | Ping (ping-pong, bounces between L and R) |
             Tape (wow/flutter pitch wobble, saturation and softened highs) |
             P+T (ping-pong and tape)

PAGE 5  REVERB  (stereo plate reverb)
   K1 Mix
   K2 Size   Tail length: from about 1.7 s to about 27 s (the maximum is very
             long!)
   K3 Damp   Darkens the tail (from 14 kHz down to 700 Hz)
   K4 Pre    Pre-delay, 2 to 250 ms

PAGE 10 JUMP  (random jump settings)
   K1 Min    Minimum interval between jumps, 50 ms to 5 s
   K2 Max    Maximum interval between jumps, 50 ms to 5 s
             (if Min is greater than Max they swap by themselves)
   K3 Win    MINIMUM window length, 1% to 100% of the K4 value.
             At 100% the window does not change; at 10% each fragment is
             between 10% and 100% of K4.
   Defaults: Min 50 ms, Max 5 s, Win 10%.
   (The jump is switched on with the A and B keys, see section 7.)


--------------------------------------------------------------------------------
 9. MASTER EFFECTS AND RECORDER (pages 6 to 9)
--------------------------------------------------------------------------------
Master chain (everything you hear goes through here):
   Drive > Filter > Delay > Reverb > Limiter

The limiter (ceiling around 0.9, soft knee) is ALWAYS on and is not shown on
screen.

PAGE 6  FILTER    same as page 3 (Mix, Sweep, Reso)
PAGE 7  DELAY     same as page 4 (Mix, Time, Fdbk, Mode)
PAGE 8  REVERB    same as page 5 (Mix, Size, Damp, Pre)

PAGE 9  DRIVE  (aggressive distortion)
   K1 Mix
   K2 Drive  Gain from 1 to 2000 times (up to +66 dB)
   K3 Tone   Tone filter after the distortion, 600 Hz to 16 kHz
   K4 Edge   Distortion character, in four stages:
                soft > hard > fold (wavefolder) > double fold
             Double fold folds the signal again and produces very dense
             harmonics.

MASTER RECORDER
   C key (note 60): start / stop. Records in stereo, 24 bit, the same thing that
   goes to the output (after the limiter), into the "master recs" folder, as
   rec_001.wav, rec_002.wav, etc. Numbering continues between sessions (the
   counter.txt file stores the last number). The screen shows REC m:ss.

   Recording gain (the C key of the upper octave, note 72): each press moves one
   step: 0, +6, +12, +18, +24 dB and back to 0. It starts at +12 dB. The
   recording goes through its own limiter, so raising the gain does not cause
   digital clipping. It does not change what you hear, only what is recorded.
   If the file sounds squashed or saturated, go down one step.


--------------------------------------------------------------------------------
 10. MIDI
--------------------------------------------------------------------------------
On the Organelle enable Settings > MIDI Setup > Midi In: Enabled (Omni channel
or your controller's channel).

NOTES 60 TO 83
  Incoming MIDI notes are mixed with the Organelle's keys: a note with velocity
  above 0 is "key pressed" and velocity 0 (or note-off) is "released". Hold
  functions (record, glitch) work the same.

CONTROLS HANDLED BY THE ORGANELLE SYSTEM
  CC 25 = AUX (64 or more = pressed)   CC 64 = footswitch   CC 21 to 24 = K1 to K4

CC 40 TO 63 = KEYS 60 TO 83 (for controllers without notes: buttons, pedalboards)
  CC 40 + n is the same as key 60 + n. Value 64 or more = pressed, below 64 =
  released. A repeated value does not trigger twice. Works on any channel.

   CC 40  Master recorder (C)          CC 41/43/46/48  Select loop 1/2/3/4
   CC 42  Glitch loop (hold)           CC 44  Glitch all 4 (hold)
   CC 45  Freeze loop                  CC 47  Freeze all 4
   CC 49  Random jump loop             CC 51  Random jump all 4
   CC 52  Recording gain               CC 50/53/55/58  Play/stop loop 1/2/3/4
   CC 60  Record loop (hold)           CC 62  Record all 4 (hold)
   CC 63  Clear (with AUX: all 4)


--------------------------------------------------------------------------------
 11. CPU SAVING
--------------------------------------------------------------------------------
The heavy effects (granular, glitch, delay and reverb, in the loops and in the
master) are switched off while their Mix is 0, and use no CPU.

   * Raising an effect's Mix turns it on instantly.
   * Lowering the Mix to 0 turns it off after a short wait:
        granular and glitch: 0.1 s     reverb: 1.3 s     delay: 1.7 s
     (delay and reverb use that time to empty their tails, so that old
     leftovers do not sound when you turn them on again). If you raise the Mix
     again before it ends, the effect simply stays on and nothing is lost.
   * Freezing grains or manual glitch turn their effect on even if Mix is 0.
   * If a delay or reverb was off and you turn it on again, it starts empty.

Saving: about 72% of the audio objects are in those effects; with all of them
off only 28% stays active. With one reverb per loop and the master reverb on,
61% stays active. If you turn on all the effects of all loops and the master at
once (the worst case) there is no saving: in a test before this version, with
everything active, the maximum was 75% CPU on the Organelle M. These figures are
proportions of the audio load, not CPU measurements of this version.


--------------------------------------------------------------------------------
 12. TIPS AND TROUBLESHOOTING
--------------------------------------------------------------------------------
* An effect "makes no sound": check that its Mix (K1 on its page) is not at 0
  and that you crossed the knob's stored value (takeover).

* Granular and glitch read from the loop itself: they need a recorded, playing
  loop.

* Reverb with very high Size and high Mix can saturate the mix; lower Size or
  the Mix.

* If the master recording sounds quiet or squashed, change the recording gain
  with the C key of the upper octave.

* If the master recording fails or has dropouts, check that "master recs"
  exists inside the patch folder and that the Organelle has free space.

* Input monitoring starts on; turn it off with AUX if there is feedback or you
  do not want it.

* To always get back to a known place, click the encoder: it goes to page 0.


--------------------------------------------------------------------------------
 13. TECHNICAL DATA
--------------------------------------------------------------------------------
* Loops: 4 stereo tracks, 3 ms to 24 s, free (no BPM).
* Memory: about 38 MB for the 4 loops of 24 s.
* Master recorder: 24-bit stereo WAV, gain 0 to +24 dB.
* Reverb: stereo plate reverb (Dattorro type), built in standard Pd.
* Drive: gain up to 2000 times, 4 character stages.
* Everything is standard Pure Data (no externals). Tested in simulation; actual
  behavior on the device depends on the Organelle's Pd version.

Version 1.0
